⚠️ Potential issue | 🟠 Major

Layout example conflicts with your own “module root” rule.

Lines 77 and 99 define root placement, but the diagram puts module.yaml/module-help.csv under skills/. That conflicts with the manifest example (source: "./") and can lead to incorrect repository structure.

 my-module/
 ├── .claude-plugin/
 │   └── marketplace.json
-├── skills/
-│   ├── module.yaml             # Registration manifests at module root
-│   ├── module-help.csv
-│   ├── my-agent/
-│   │   ├── SKILL.md
-│   │   ├── prompts/
-│   │   └── scripts/
-│   └── my-workflow/
-│       ├── SKILL.md
-│       └── prompts/
+├── module.yaml                 # Registration manifests at module root
+├── module-help.csv
+├── my-agent/
+│   ├── SKILL.md
+│   ├── prompts/
+│   └── scripts/
+├── my-workflow/
+│   ├── SKILL.md
+│   └── prompts/
 ├── README.md
 └── LICENSE

Based on learnings: "Applies to */module.yaml : Module metadata must be defined in module.yaml at the root of the module with installation config and variables".

Verify each finding against the current code and only fix it if needed.

In `@docs/how-to/distribute-your-module.md` around lines 77 - 100, The diagram
contradicts the “module root” rule by showing module.yaml and module-help.csv
under skills/; update the example tree and surrounding text so module.yaml and
module-help.csv are placed at the actual module root (next to
.claude-plugin/marketplace.json), and make the manifest example (e.g., source:
"./") consistent with that layout; specifically revise the ASCII tree to show
module.yaml and module-help.csv at my-module/ (not inside skills/), and adjust
any explanatory lines that reference “module root” to match this placement.

⚠️ Potential issue | 🟡 Minor

Fix manifest location wording in capability summary.

Line 323 says marketplace.json is generated at the module root, but this file later documents .claude-plugin/marketplace.json. Align this row to avoid incorrect file placement guidance.

-| **Create Module**   | CM        | Generate `module.yaml`, `module-help.csv`, and `marketplace.json` at the module root (or bundled into a skill for direct-download distribution) |
+| **Create Module**   | CM        | Generate `module.yaml`, `module-help.csv`, and `.claude-plugin/marketplace.json` (or bundle manifests into a skill for direct-download distribution) |

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/builder-commands.md` around lines 323 - 324, Update the
"Create Module" capability summary row (label "Create Module" / "CM") to correct
the manifest location wording: replace the claim that marketplace.json is
generated "at the module root" with the accurate path (for example
".claude-plugin/marketplace.json") or clarify that it is placed under the
.claude-plugin directory (or bundled into a skill for direct-download
distribution), so the row consistently references module.yaml, module-help.csv,
and the .claude-plugin/marketplace.json location.

docs/explanation/module-configuration.md:55 — This page mentions _bmad/config.toml / config.user.toml earlier, but here it documents config.yaml / config.user.yaml as the registration outputs. Consider making the file format/extension consistent across the page so users don’t write config to the wrong filenames.

Severity: medium

⏳ Generating Fix in Augment link...

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

docs/reference/builder-commands.md:370 — This says Create Module’s default output is root module.yaml/module-help.csv with no setup skill/merge scripts, and VM auto-detects that layout, but the current Module Builder assets/scripts in this repo still scaffold/validate the *-setup/assets/ (or standalone assets/) layouts. If the tooling behavior hasn’t changed yet, these docs may mislead users about what CM/VM will generate/accept.

Severity: medium

⏳ Generating Fix in Augment link...

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

docs/how-to/distribute-your-module.md:77 — The text calls for manifests at the “module root”, but the single-module example places module.yaml/module-help.csv under skills/ while the manifest example uses plugins[].source: "./". Consider clarifying which directory is treated as the module root by the installer so readers don’t end up with a valid marketplace manifest but manifests in an unexpected location.

Severity: low

⏳ Generating Fix in Augment link...

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}